home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / lang / FPL_v147.lha / fpl / funclib / README < prev    next >
Text File  |  1994-04-29  |  4KB  |  135 lines
  1.                FUNCLIB DEVELOPMENT
  2.                ===================
  3.  
  4.   This directory contains source files to create a fully functional funclib
  5. that works with fpl.library version 7 and later.
  6.  
  7. CODE
  8. ----
  9.   Anyone can and may do a funclib. Just cut and paste from my examples and you
  10. should be able to make one in a very short time.
  11.  
  12. STYLE GUIDE
  13. -----------
  14.   When you add functions with your own funclib, remember that to enable almost
  15. anyone to add those function names while their FPL session is running, the
  16. names you use must be unique! Therefore, I encourage you all to chose names
  17. which uses an acronym of the funclib name as a prefix or likewise (just like
  18. I have done with the fpl.library function names). If your funclib is called
  19. "foobar", call your functions fb_OpenWindow(), fb_CloseWindow() and so on...
  20.  
  21.   Name your funclib in the form "<name>.funclib" with only lowercase letters!
  22.  
  23.   Make sure your program handles cases where a function name is already used!
  24.  
  25. STARTUP
  26. -------
  27.   The funclib should have an executable file placed in FPLLIBS: with the name
  28. of the funclib. In our example source, the name of the funclib and the
  29. executable is "func". This file is invoked both when the funclib is opened and
  30. when it is closed.
  31.   The executable file is, when the funclib is opened, started with three
  32. parameters. They are in the order of appearance:
  33.  "open"    - tells that the funclib is to be opened
  34.  <anchor>  - the FPL session anchor
  35.  <version> - the lowest acceptable version number of the funclib.
  36.  
  37.   It is then up to the program to add functions to the FPL session. In my
  38. examples, this program starts another program ("lib") asynchronously and
  39. communicates with it through a named message port. Keep on reading for more
  40. details.
  41.  
  42. CLOSE
  43. -----
  44.   When the funclib gets order to close down, it is started with two parameter:
  45.  "close"  - tells that the funclib should close
  46.  <anchor> - the FPL session anchor
  47.  
  48.   In my example source, the program then tells "lib" to remove everything and
  49. exit.
  50.  
  51. MY SOLUTION
  52. -----------
  53.   You can of course make the funclib work in several ways. The funclib is
  54. started as described above to make the funclib programmer as independent as
  55. possible. The funclib takes care of its own workings.
  56.  
  57.   My solution works like the following little scheme will try to explain:
  58.  
  59. 1. The funclib "func" is opened (should be named "func.funclib"!) and the
  60.   program "FPLLIBS:func" is run:
  61.  
  62.   |--------|
  63.   |  func  |
  64.   |--------|
  65.  
  66. 2. Func starts another program called "lib", which adds all functions that
  67.   this lib should add to the FPL session:
  68.  
  69.   |--------|        |--------|
  70.   |  func  | =====> |  lib   |
  71.   |--------|        |--------|
  72.  
  73. 3. "lib" tells "func" through the named message port that it has done all
  74.   initial work and that "func" can return:
  75.  
  76.   |--------|          |--------|
  77.   |  func  | <--OK--  |  lib   |
  78.   |--------|          |--------|
  79.  
  80. 4. "func" exists (and returns success to FPL), and "lib" is left in memory,
  81.   waiting for instruction sent to the message port:
  82.  
  83.   |--------|
  84.   |  lib   |
  85.   |--------|
  86.  
  87. 5. When the funclib is closed, "func" is started again.
  88.  
  89.   |--------|        |--------|
  90.   |  func  |        |  lib   |
  91.   |--------|        |--------|
  92.  
  93. 6. It uses the message port to tell "lib" to clean up and exit.
  94.  
  95.   |--------|          |--------|
  96.   |  func  | -EXIT->  |  lib   |
  97.   |--------|          |--------|
  98.  
  99. 7. "lib" returns a message to "func" when it has cleaned up the FPL parts and
  100.   "func" can return to FPL.
  101.  
  102.   |--------|          |--------|
  103.   |  func  | <-DONE-  |  lib   |
  104.   |--------|          |--------|
  105.  
  106. 8. Both "func" and "lib" exits.
  107.  
  108. RETURN CODES
  109. ============
  110.  
  111.   The funclib return codes describe the progres to the invoking FPL. Use the
  112. return codes from the "funclib.h" file.
  113.  
  114. SOURCE DESCRIPTION
  115. ==================
  116. (all files are in the funclib/ directory)
  117.  
  118. smakefile
  119.     makefile for the two funclib programs and the test program
  120.  
  121. func.c
  122.     This file controls (starts and stops) the actual lib.
  123.  
  124. lib.c
  125.     This is the actual lib. This program adds functions to the anchor
  126.     supplied from FPL.
  127.  
  128. test.c
  129.     Test program source. (start it with "test test.fpl" for testing of
  130.     the "func" funclib.)
  131.  
  132. test.fpl
  133.     Test FPL program that uses the test funclib and the test funclib
  134.     function.
  135.